Log In Using Google OAuth Authentication

On Android, Apple and Windows devices users can log in using Google OAuth rather than a Digitise Apps username or Windows Active Directory Authentication. This means that users can login using a Google Gmail address and its corresponding Google account password. Digitise Apps will authenticate the user with Google and if valid will allow access to the user.

OAuth authentication is only available on Windows devices if they are running the Windows Desktop version of the Digitise Apps Client. It isn't available in the Universal Client or Universal Standalone Apps.

In order to use OAuth Authentication, each user will require a Gmail account as the Gmail address is used as the username within Digitise Apps. You will also need to create Google Credentials in the Google API Console, if you have not already got this set up to use OAuth elsewhere. Having done this, you can then configure the required users in App Manager and configure your Digitise Apps Client or Standalone Apps to use OAuth. If you are building Standalone Apps and pre-configured Clients, you can configure them to use OAuth within the build request options in App Studio. OAuth users can be allocated access permissions to your Digitise apps in the same way as Digitise Apps and Active Directory users can within App Manager.

In addition, in order to login using OAuth, both the App Server machine and the Client devices will require an internet connection.

If you configure a Digitise Apps Client or Standalone App to use Google Authentication, the first time the Client/Standalone App loads, Digitise Apps will display the Google login in a browser window instead of the standard Digitise Apps login dialog. The user will be asked to enter their Gmail e-mail address and then their Google account password. This login and authentication is handled by Google and not by Digitise Apps.

Note that on the Windows Desktop Platform, Digitise Apps will display a Google Login dialog box within the Client window in addition to the separate browser window. This dialog allows you to cancel the login within Digitise Apps should the browser window not appear or if you were to experience problems logging in to Google.

If you enter a valid e-mail address and password, Google will inform Digitise Apps that you are a valid user and passes Digitise Apps an access token. You will then be logged in to the Digitise Apps Client/Standalone App, providing your OAuth user has been configured in App Manager. The browser window and, on Windows devices, the Digitise Apps Google Login dialog box should both automatically be closed.

If you attempt to login using a Gmail address that hasn't been added into App Manager, an error message will be displayed and you will not be logged in to the Digitise Apps Client/Standalone App.

Once a user has logged in to Digitise Apps via OAuth, Digitise Apps will also automatically revoke the token if you log out of a Digitise Apps Client, close down a Digitise Apps Client, close down a Standalone App or stop the app within a running Standalone App without closing down the Standalone App. If you log in, restart an app or load the Digitise Apps Client or a Standalone App after the token has been revoked, Digitise Apps will re-authenticate you with Google OAuth.

Note that on iOS devices, if you are running a Standalone App that contains multiple primary Digitise apps' Models, the token is only revoked when you close the Standalone App, closing a running app without closing down the Standalone App does not revoke the token.

Generally, re-authenticating will result only in the Google page asking you to choose the account you want to use. On occasion, however, you may be required to re-enter your Gmail address and password as well. When re-authenticating, you can choose to login as a different OAuth user.

If you want to be able to log in such that the re-authentication doesn't require user interaction, you can use the Save Password option in the Digitise Apps Client/Standalone App's Settings. Selecting this option will cause Digitise Apps to automatically log in the last user again without displaying any of the Google web pages, as long as the current access token is valid. If the token has become invalidated, Digitise Apps will need to re-authenticate the user with Google and the browser page(s) will be re-displayed.

If a user logs in to a Digitise Apps Client or Standalone App using OAuth, if you look in the Settings the currently logged in user will appear as that user's Gmail address. Once logged in using OAuth, apart from token renewal, there is no difference in the way Digitise Apps behaves for OAuth users than it does for users logged in using other supported methods of authentication.

In order to log in using OAuth the mobile device must have a connection in order for Digitise Apps to authenticate the user with Google over the internet. Once a user has logged in successfully, if the connection goes down any running apps will continue to work, although a user won't be able to synchronise data with a remote Data Source, of course, until they have a network signal again. If the user does anything which revokes the access token as discussed above, e.g. closing a Standalone App, the value of the Save Password option determines whether the user will be able to log back in again whilst the network connection is down. If Save Password is selected, Digitise Apps will automatically log the user in using the last logged-in user's credentials, providing that the current access token has been created or refreshed within the last hour. The user will be able to run their apps but as long as no network signal is available will not be able to synchronise data with remote Data Sources. If the token is more than an hour old or if Save Password is not selected the user will get an error message informing them that there is no internet connection available and they will not be able to log in or load or start apps.

The Scripting Method, GetAccessToken, allows you to obtain the access token within a Script, e.g. allowing you to pass it to a remote web service Data Source so that that web service can authenticate the user.